API review
Proposer: John Hsu
Present at review:
- List reviewers
Newly proposed, mistyped, or obsolete package. Could not find package "gazebo" in rosdoc: /var/www/docs.ros.org/en/api/gazebo/manifest.yaml
Revised API
Services
Overall Simulator Properties
/gazebo/get_world_properties
/gazebo/pause_physics
/gazebo/unpause_physics
/gazebo/get_physics_properties
/gazebo/set_physics_properties
Model Manipulation
/gazebo/get_model_properties
/gazebo/get_model_state
/gazebo/set_model_state
Joint Manipulation
/gazebo/apply_joint_effort
/gazebo/get_joint_properties
/gazebo/set_joint_properties
/gazebo/apply_body_wrench
![/!\](/moin_static197/rostheme/img/alert.png "/!\")
/gazebo/clear_body_wrenches - clears all applied wrenches for a body - /gazebo/clear_joint_forces - clears all applied forces for a joint
Link Manipulation
/gazebo/get_link_properties
- /gazebo/set_link_properties - ability to alter body mass on the fly
- /gazebo/get_link_state - get pose and twist of the link
/gazebo/set_link_state
Spawn Delete Model
/gazebo/spawn_gazebo_model
/gazebo/spawn_urdf_model
/gazebo/delete_model
Topics
/gazebo/set_link_state
/gazebo/set_model_state
- /gazebo/link_states broadcast LinkStates message containing states of all links
- /gazebo/model_states broadcast ModelStates message containing states of all models
(REVIEWED) Proposed ROS services API (REVIEWED)
- gazebo style API's
- spawn_model - given a model name and some string, determines if the string is filename/parameter name/GazeboXML/URDF, then spawn model with an initial pose. Option to specify another model name as dependency, such that the current model will not be spawned unless the dependent model exists in simulation already. For example, to spawn a cup, one could designate table as the dependent model.
- delete_model - given a model name, delete it from simulation. Option to specify a dependent model, will not delete until the dependent model is deleted first.
- get_gazebo_model_info - get back info about the gazebo model. Get canonical body, list of bodies, list of joints, parent model, children models. (Gazebo XML?). etc.
- get_gazebo_model_state - get pose and twist of the gazebo model.
- get_gazebo_world_info - get back information about the world in general. List of models in the world.
- get_gazebo_physics_info - get back physics engine configuration info.
- set_gazebo_physics_info - updates physics engine configuration.
set_gazebo_body_wrench - applies a wrench on a body. Start at start_time and lasts for duration seconds.
- set_gazebo_joint_info - sets gazebo joint properties such as stopERP, stopCFM, etc.
set_gazebo_model_state - set pose, twist of the gazebo model. this effectively sets the canonical body pose and twist. An optional relative_entity_name specifies what reference frame to set target pose and twist.
- urdf/ROS style API's
- get_link_info - link properties such as inertia and link state.
- set_link_state - for now, we'll ignore the case that if link is connected to another link via a joint. Correct way to handle this is to to propagate changes.
- set_link_wrench - applies a wrench on a link (gazebo body).
- get_joint_info - joint properties such as type, damping etc. and joint state.
set_joint_effort - sets joint force or torque, given specific start_time and duration in seconds.
- set_joint_properties - set dynamic joint properties such as friction and damping coefficients.
Question / concerns / comments
Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.
- Eitan
- I worry that the spawn_model service will be a bit difficult to use just because it will be unclear from the service definition what the special string should be used for. I suppose that with proper documentation, it'll probably work, though the alternative would be to create 4 separate spawn_model services. That might be more explicit. For example, what will you do now if you have a filename that is also a parameter name?
(John) good point. We can either split this into 6 services or adding a req.model_xml_type enum:
uint8 model_xml_type # can be URDF, GAZEBO_XML, FILENAME, PARAM uint8 URDF = 0 # enum for model_xml_type uint8 GAZEBO_XML = 1 # enum for model_xml_type uint8 URDF_FILE = 2 # enum for model_xml_type uint8 URDF_PARAM = 3 # enum for model_xml_type uint8 GAZEBO_XML_FILE = 4 # enum for model_xml_type uint8 GAZEBO_XML_PARAM = 5 # enum for model_xml_type
For clarity, I think GetGazeboModelInfo shoud be GetGazeboModelState.
(John) I wanted Info to convey static model properties such as inertia, and State to represent dynamic properties such as pose, twist, etc. I split out pose/twist into a separate service GetGazeboModelState and kept the rest in GetGazeboModelInfo for now.
- I'm not sure that the Set*Info services make sense. I like the use of the word State better, but I think it should be either State or Info and not both. Did you intend for state and info to convey different meanings?
- I worry that the spawn_model service will be a bit difficult to use just because it will be unclear from the service definition what the special string should be used for. I suppose that with proper documentation, it'll probably work, though the alternative would be to create 4 separate spawn_model services. That might be more explicit. For example, what will you do now if you have a filename that is also a parameter name?
- Wim
- in which frame are Ixx, Ixy, etc specified?
(John) I added comments in GetLinkInfo.srv
- Why is the center of mass location a pose and not a vector?
- (John) com specifies offset and orientation of the inertia matrix, so the rotation specifies orientation of the Ixx, Ixy, etc. Similar to what's done in the URDF with the origin tag.
- in which frame are Ixx, Ixy, etc specified?
- Universal joint only has 2 DOF?
- (John) Updated ball joint to 3 DOF in comment
- Universal joint only has 2 DOF?
Specify wrench/twists better: reference frame, reference point, between which bodies is wrench/twist applied? --> SetGazeboBodyWrench, SetGazeboModelState, SetLinkWrench, ...
- What happens if spawn/delete dependencies are not satisfied? Will the model automatically get spawned/deleted when the dependency gets satisfied at a later time?
- (John) yes
- How do you queue multiple spawn/delete requests for the same model?
- (John) if spawn is requested for a model that has already been spawned, the service returns failure with some nice error messages.
- Josh F
- Why do some of the service names include "gazebo" and some not?
- (John) the settings that are gazebo-specific have "gazebo" in it.
- I'd like to see topic versions for any of the "set" functions so that they are non-blocking
- (John) I implemented some of these interfaces such as spawn/delete/force and wrench application as 'non-blocking services', by adding specific jobs to an internal scheduler. User can specify dependency or start_time for the event to occur at a later time.
- Info vs. State is confusing -- don't have a better solution though.
- (Bhaskara) Maybe Parameters instead of Info?
- (John) Parameter might be confusing with ROS parameters?
- (Bhaskara) Maybe Parameters instead of Info?
- Why do some of the service names include "gazebo" and some not?
- Bhaskara
- Do we need a success flag in every service definition?
- On a similar note, I think having a string status message in all the return values clutters up the API. Can we just use rosout for this?
- Maybe have a separate boolean flag for the duration=0 cases for applyWrench and setJointEffort
Maybe rename setJointEffort -> applyJointEffort
- (John) I like it, will update services
- What are the semantics of changing the state in a physically inconsistent way, e.g., making two models interpenetrate?
- (John) we're not checking for collisions in these services at this time.
Can we have a way to set multiple model states in a single timestep (e.g., simultaneously move the table and cup rather than one at a time, which would leave the cup hanging in mid air temporarily). For example, maybe have PauseTime and UnpauseTime services?
(John) Good idea, I'll add services pause_simulation. Alone the same line, maybe a way to manipulate simulation time on the fly. Not sure how ROS is designed with times that are not monotonically increasing?
- One use case for modifying simulator state is for simulating grasping by temporarily attaching objects to the gripper. Is there an easy way to do this using the current api?
(John) not right now, but I can add a service spawn_gazebo_joint?
Meeting agenda
To be filled out by proposer based on comments gathered during API review period
Conclusion
Stack status change mark change manifest)
- Action items that need to be taken.
Major issues that need to be resolved Spawn / delete calls:
Make spawn / delete service calls block until the action is taken, and return meaningful response to clients (success vs. failure).
Remove dependencies
- Might eventually end up writing a script to help with spawning models in order
TODO: resolve Wrench (and possibly Twist) messages, perhaps combining gazebo-specific and non-gazebo-specific messages.
Remove the string "Gazebo" from service / message names
Create topic versions of the set_ service calls that are specific to a body or link.
Replace _info with _properties
Make the type of any time and duration fields time and duration.
Add pause_simulation and unpause_simulation (or maybe just pause_simulation with a bool pause field inside it).
Split spawn into two calls: one for Gazebo XML (SpawnGazeboModel) and one for URDF XML (SpawnURDFModel). Each will just take XML in. The caller is responsible for reading from disk or the param server if necessary. You can use the same SpawnModel.srv file for both services.
